 ______________________________________
|                                      |
|                                      |
|                 ,'`.                 |  Pin Eight NES Tools
|               ,'    `.               |
|             ,'  ,'`.  `.             |  Version 0.3
|           ,'  ,'    `.  `.           |
|         ,'  ,'  ,'`.  `.  `.         |
|       ,'  ,'  ,'    `.  `.  `.       |
|       `.  `.,'  ,'`.  `.,'  ,'       |  by
|         `.  `,,'    `.  `.,'         |
|         ,'`.  `.    ,'`.  `.         |  Damian Yerrick
|       ,'  ,'`.  `.,'  ,'`.  `.       |
|       `.  `.  `.    ,'  ,'  ,'       |
|         `.  `.  `.,'  ,'  ,'         |
|           `.  `.    ,'  ,'           |
|             `.  `.,'  ,'             |
|               `.    ,'               |
|                 `.,'                 |
|                                      |
|______________________________________|
                                     TM

<legal>

Copyright  2002 Damian Yerrick <tepples@spamcop.net>.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU Free
Documentation License" (http://www.gnu.org/licenses/fdl.html).

THE DOCUMENT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, OR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS DOCUMENT.

UNIX is a registered trademark of The Open Group.
Windows is a registered trademark of Microsoft Corporation.
Linux is a registered trademark of Linus Torvalds.
Nintendo, NES, Game Boy, Virtual Boy, and Super NES are trademarks of
Nintendo.
Sega and Genesis are trademarks of Sega.
Apple and Mac are trademarks of Apple Computer Inc.
The Pin Eight logo is a trademark of Damian Yerrick.

</legal>




=== System requirements ===

Your system must be compatible with the Allegro library.
This means that the tools are likely to run on these systems:
 o 486 and faster DOS systems with 4 MB or more of RAM and a DPMI
   extender such as CWSDPMI
 o Windows 9x
 o Windows 2000, XP, Vista?
 o Linux, BSD (including Mac OS X), and UNIX systems with X11


=== Compiling Pin Eight NES Tools ===

You need
 o GNU C Compiler for your target platform
   http://gcc.gnu.org/ (GCC home page)
   http://www.delorie.com/djgpp/ (DJGPP, a port of GCC to DOS)
   http://www.mingw.org/ (MinGW, a port of GCC to Win32)
 o the Allegro library, version 4.x
   http://alleg.sourceforge.net/

To compile it on DOS and Windows, pull up a command prompt, bring
your compiler into the PATH, and type
  make -f makefile.dj

On Linux
  make -f makefile.unix

If you use other programs called "ted" or "name", you will want to
rename the executables to "8ted" and "8name".


=== 8TED ===

Older video game consoles (1984 to 1991) store their graphics as
8-by-8-pixel tiles.  Most paint programs do not support the formats
these consoles use.  That's why there's 8TED.  When it's finished, it
will be able to translate between raster bitmap formats used by PCs
and tile formats used by game consoles.  It can already edit the
graphics of many games directly in the ROM file (that is, if they
don't use in-ROM compression like many later games use).

-- Features --

pineight snowbro
  8ted   tlayer
  alleg dos win platform
                view and edit tiles in the native format of
    X    X   X  PC (1-bit)
    X    X   X  NES
    X    X   X  Game Boy and Super NES Mode 0
    X           view NES, Game Boy, and Genesis 8x16 tiles correctly
    X    X   X  Virtual Boy
    X    X   X  Super NES Mode 1
    X           Super NES 3-bit and Mode 7 packed
    X    X   X  Sega Master System
    X           Sega Genesis
    X?       X  Neo-Geo Pocket Color
    X        X  Super NES 3-bit
planned      X  PC bmp, pcx, and png graphics
             X  zoom control
    8    2  256 simultaneous open files
    X    X      edit small files without crashing
    X           create, open, close, and resize files
                within the program
             X  undo
    X        X  "Save changes?" reminder on close or quit
    X    X   X  byte-by-byte tile alignment
   256  136 n/a clipboard width
   128   64     clipboard height
    X           place tile into clipboard at any pixel location
             X  drag and drop to copy tiles
    X    X   X  rotate and flip tile in edit area
         X      repair some ROM checksums
   256  16  256 palette size
    X    X   X  palette editing with save and restore
             X  palette save as...
             X  save palette as nes or snes/gbc
    X    X      runs under DOS and WinDOS
         X      small DOS binary
    X        X  runs natively under Windows 9x and Windows NT
    X        X  runs in a window on Windows
    X           runs under X11 on Linux and many UNIX systems
    X           free software

Note that tlayer has been updated for Windows since this document
was first written.  tlayer vs. 8ted is becoming an arms race, no?
I see 8ted as nearly on par with tlayer pro on Windows systems and
way ahead of the competition on DOS and Linux.

-- Invoking --

With a command-line shell such as Bash or command.com:

ted
  Start 8TED, with a blank, untitled file of 8192 bytes.

ted smb3.nes allstars.smc zerowing.bin
  Start 8TED with those files open.  If they don't exist, 8TED will
  load them as a blank file of 8192 bytes.

ted --full smb3.nes allstars.smc zerowing.bin
  Do the same, except forcing full screen.

Modify this appropriately for how you have your copy of
8TED installed.


If your shell is Windows Explorer or something similar:

Double-click ted.exe
  Start 8TED, with a blank, untitled file of 8 kilobytes.

Drag files onto ted.exe
  Start 8TED with those files open.

Double-click a chr file, with chr associated to ted.exe
  Start 8TED with that file open.

-- Mouse commands --

All tile editing is done with the mouse.  Clockwise from left are
the buffer contents, the clipboard, the palette, and the edit area.

Left-clicking the buffer will copy a tile into the edit area.
Now, you can drag across the edit area with either mouse button and
change pixels.  Holding Control and clicking with either button in
the edit area will "grab" the color under the mouse pointer as the
corresponding pen color.  Left-clicking the palette loads a color
into the color editing area to the right of the palette (and also
sets the left-click pen color); right-clicking the palette redraws
the buffer in the colors surrounding where you right-clicked (and
also sets the right-click pen color).  When you're done editing a
tile, right-click a tile in the buffer to paste the contents of the
edit area there.

Save often (Ctrl+S).  I can't stress this enough.

In the color editing area, you can increase or decrease the levels
of red, green, and blue in the current left-click pen color.

You can copy tiles from one open file to another by using the edit
area as a temporary "clipboard," or when the full clipboard is
implemented, you can use that as a temporary holding area for tiles.
Tile copying works across formats, so you can (to an extent) steal
Game Boy and SNES graphics for your NES demo, but they'll need a bit
of redrawing, as 8TED drops high-order bits when down-converting.

-- Keyboard commands --

Up and Down arrows
  Move file offset one row at a time.

Page Up and Page Down
  Move file offset 24 rows at a time.

Left and Right arrows
  Tweak file offset. Useful when a program stores its tiles at an
  odd offset (such as some NES games that use VRAM).

+
  Increase the "height" of each tile by 8 pixels.  NES, Game Boy, and
  Genesis games store their tiles (especially sprites and fonts) in
  such a fashion that tiles adjacent in memory are stacked vertically
  rather than horizontally on screen.  PC 8x16 VGA fonts work the
  same way.

-
  Decrease the height of each tile.

F1
  Switch format.  Some Game Boy and NES programs store tiles in 1-bit
  format, and a LOT of Super NES programs store tiles in Game Boy
  format.  Hint: A PC 8x16 VGA font can be (mis)used as a Game Boy
  font and vice versa.

F2
  Write palette to `tiled.pal' in the current directory.  TED will
  reload this palette next time it starts in the same directory.

F6
  Cycle among open buffers.

Ctrl+O
  Open a file into a buffer.  Up to 8 buffers can be open at once.

Ctrl+S
  Prompt for a filename and write the current buffer there.
  SAVE OFTEN!

Ctrl+W
  Close the current buffer.  If the buffer has been modified since it
  was last written, ask before closing.

Ctrl+R
  Prompt for a new buffer size and resize the buffer accordingly.

Ctrl+Q
  Close all open files (prompting to save modified buffers).
  
H, V, R
  Flip or rotate the tile in the edit area.

X
  Exchange left-click and right-click colors in the tile.


=== 8Name ===

The "nametable" is either of two 1 KB areas of the NES PPU's RAM,
at locations $2000 and $2c00 in the PPU address space.  The term
has also come into use to describe a 1 KB data structure in ROM that
holds data to be copied verbatim into a nametable.  The structure
consists of a 32 row by 30 column array of bytes, followed by a
64-byte "attribute table" that holds information about which color
palette to use for a given tile.  (For more information, refer to NES
technical documents available on http://nesdev.parodius.com/)

8Name is a nametable editor.  It lets you draw on a nametable using
the tiles in a tile set.

-- Features --

pineight snowbro
  8name    nsa
    X       X   load NES tilesets
    X       X   edit NES nametables
    X           display entire tileset
    X           display entire nametable
    X           pick up tiles from nametable
    X           type to generate ASCII characters
    X           arrow keys and backspace to move cursor
    X       X   runs under DOS and Windows 9x
            X   small DOS binary
    X           runs natively under Windows 9x and Windows NT
    X           runs under X11 on Linux and many UNIX systems
    X           free software

-- Invoking --

8Name can be invoked two ways: with three names or with one name.

$ name t.chr title.pal copr.nam

This uses the NES CHR data in t.chr, the NES palette data in
title.pal, and the nametable data in copr.nam.

$ name --full t.chr title.pal copr.nam

This does the same thing, except forces full screen.

$ name wc

This uses the NES CHR data in wc.chr, the NES palette data in
wc.pal, and the nametable data in wc.nam.

If any palette or nametable file does not exist, 8Name will create
it using sensible defaults (the GNOME vs. KDE ingame palette, or a
blank nametable).  If the chr file does not exist or is smaller than
4096 bytes, 8Name will exit with error.

-- Mouse commands --

To set the current tile, click a tile in the tileset.

To set the current attribute, click a part of the color palette.

To set the current tile AND attribute, right-click a tile in the
nametable.

To draw in the current tile and attribute, left-click in the
nametable.  Note that the behavior of left- and right-clicks is
backwards with respect to actions in 8TED's buffer, but it is
consistent with the graphic editors in Clickteam products.

-- Keyboard commands --

Ctrl+S
  Save the current .nam file.  Save often.

Ctrl+Q
  Exit the program.  It currently does not prompt to save a modified
  .nam file.

ASCII printable characters (space to ~)
  Write the typed ASCII character to the tile under the mouse
  pointer, then move the mouse pointer one tile to the right.

Arrow keys, backspace
  Move the mouse pointer by one tile in that direction.


=== bmp2nes ===

bmp2nes converts grayscale bitmaps or indexed 4-color bitmaps into
.chr files usable by the NES PPU.  It supports .bmp and .pcx images.

-- Invoking --

bmp2nes [-d] file [file...]

This will convert one or more bitmaps to chr format.

If -d is specified, bmp2nes will treat the bitmaps as grayscale
images and use Bayer dithering to take them down to 2 bpp.

If -d is not specified, bmp2nes will use the two low-order bits
of each color value.  This means that for example, color values of
1, 5, 9, 13, etc. get mapped to NES color 1.

Examples:

  bmp2nes leia.bmp luke.bmp
  bmp2nes -d apple.bmp pear.bmp


=== chropt ===

Given a .chr file, chropt finds and eliminates duplicates from the
.chr file and creates a .nam file containing a nametable that will
reconstruct the .chr file.  If the .chr file was 32 tiles wide, the
.nam file will be suitable input to Name.

-- Invoking --

$ chropt titlesc.chr

Analyzes titlesc.chr for duplicate tiles.  Creates out.chr and
out.nam, which your 'make' script can rename, compress, or do
whatever with.


=== PackBits ===

Apple introduced the "PackBits" format for run-length encoding of
data with the release of MacPaint on the Apple Macintosh computer.
This program packs a raw binary file into a Pin Eight PackBits
format file.

-- Invoking --

$ packbits INFILE OUTFILE

Packs INFILE to OUTFILE.

-- Format --

The Pin Eight PackBits file format consists of a two-byte header
giving the number of decompressed bytes in big-endian format,
followed by a PackBits data stream.  A PackBits data stream
consists of packets of one byte of header followed by data.
The header is a signed byte; the data can be signed, unsigned,
or packed (such as MacPaint pixels).

Header byte     Data
0 to 127        1 + n literal bytes of data
0 to -127       One byte of data, repeated 1 - n times in the
                decompressed output
-128            The compressor must not generate this value as a
                packet header, and the decompressor must ignore it.

Note that interpreting 0 as positive or negative makes no difference
in the output.  Runs of two bytes adjacent to non-runs are typically
written as literal data.

The file unpkb.asm is available for use under the mit license.


=== Bugs ===

-- Probably fixed --

8TED:
Neo-Geo Pocket Color support probably works (it's been verified
against Tile Layer Pro) but has not been tested on real NGPC ROMs
because I don't have an NGPC system.

-- Unfixed --

All but 8TED and 8Name:
Does not respond to --help or --version args.

8TED:
Does not import .bmp, .pcx, or .png graphics.

8TED:
No support for the format F-Zero uses for floor tiles.  The
format seems to be based on Sega Genesis (!) with a 17-byte
stride (does the extra byte contain the top 4 bits?), a logical
choice for expansion into Mode 7's native 8-bit packed form.

8TED:
Cannot independently set "Lock to 8 pixels" per buffer.

8TED:
Cannot scale between 8x8 and 16x16.

8Name:
Cannot edit the NES palette.  Eventually, right-clicking the
palette in the tool bar will let you edit the palette.

8Name:
Does not prompt on quit for saving changes to a .nam file.

-- Won't fix --

8TED:
No ROM checksum support.  There are better tools for that at
any ROM hacking site.

8TED:
No support for oddly interleaved or compressed graphics.  Again,
Zophar's has tools to decode common console formats, or you can write
your own interleaver in C or Basic for arcade ROMs.  Some games such
as Contra, and Zelda, and Who's Cuter use a simple run-length encoded
lossless format, whereas titles for later systems often use lossy
encoding, especially for large animations.

8TED, 8Name:
Does not anticipate when you want to save the file.  Save often.

All:
DOS executables are large. Won't fix because the source is a small
download, most of the exe is library code (that's the price you pay
for portability), and you can get bigger hard drives at
pricewatch.com.

All:
Doesn't run on 8088/8086 (old-skool PC and XT) or 286 (AT).

All:
Doesn't run on DOS machines without support for VESA or VBE/AF.
You can get VBE/AF drivers for your video card at
  http://www.talula.demon.co.uk/freebe/


If you find bugs, please notify Damian Yerrick <tepples@spamcop.net>.



=== Changelog ===

0.4: (2008)
     8TED includes exchanging the left- and right-click colors
     (press X).
     8Name uses a better NES palette and doesn't overlap the GUI
     colors with the NES colors.
     8Name allows moving with the arrow and backspace keys.
     8TED and 8Name respond to --help and --version.
     8TED and 8Name respond to --full, allowing to force full screen
     if your monitor is too blurry or too high DPI for windowed mode.
     Upgraded to Allegro 4.2.2.

0.3: Released on October 15, 2002 or so
     TED is now 8TED because of collision with another program.
     8TED now supports control-clicking the edit area to grab a pen
     color.
     The distribution, now called Pin Eight NES Tools, also includes
     8Name, bmp2nes, chropt, and packbits.
     Expanded documentation.

0.2: Damn.  I was searching zophar.net for some Genesis tools and
     found that there was already an editor named what my editor used
     to be named.  This seems to happen every single time I release
     something (Carbon, anyone?).  Now I understand why marketing is
     paid so well to come up with unique trademarks.
     Added preliminary NGPC and SNES 3-bit support.
     Checking 'Snap to 8 bits' now redraws the clipboard and checkbox
     regardless of whether a clipboard tile is being edited.
     Resizing now redraws the status bar and file display.

0.1: Initial private release to nesdev.  At least Chris Covell,
     author of Solar Wars, liked the 8x16 feature.
